Docs: Restructure write support into explicit operation subsections#3647
Open
Zhuoxi2000 wants to merge 1 commit into
Open
Docs: Restructure write support into explicit operation subsections#3647Zhuoxi2000 wants to merge 1 commit into
Zhuoxi2000 wants to merge 1 commit into
Conversation
Documents the two write API modes (Table API vs Transaction API) and gives each write operation its own subsection: Append, Overwrite (full and partial), Dynamic partition overwrite, Delete and Upsert. Pads in previously undocumented details: multi-operation atomic commits via Transaction, the snapshot_properties / branch kwargs accepted by every write, case_sensitive on filtered operations, the DELETE/OVERWRITE/APPEND snapshots an overwrite or delete may produce, the no-match warning on delete, and the copy-on-write fallback when write.delete.mode is merge-on-read. Closes apache#1008
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1008
Rationale for this change
#1008 asks for the write documentation to describe each operation and API
mode "explicitly in detail as separate subsections". The current "Write to
a table" section is a single narrative: delete is buried mid-flow, the
Transaction API is never mentioned for writes, and several parameters
(
branch,snapshot_properties,case_sensitive) are undocumented.What changes are included in this PR?
TableandTransaction" — documentsthat every Table-API write is a single-operation transaction, and shows
multi-operation atomic commits (
delete+appendin one snapshot chain,schema evolution + write in one commit).
partial), Dynamic partition overwrite (split out of "Partial
overwrites"), Delete (new — previously inline prose), Upsert
(unchanged).
snapshot_properties/branchkwargs acceptedby every write,
case_sensitiveon filtered operations, theDELETE/OVERWRITE/APPEND snapshots an overwrite/delete may produce, the
"did not match any records" warning, and the copy-on-write fallback when
write.delete.mode=merge-on-read.No code changes; prose and structure only. Existing anchors are preserved
("Partial overwrites" survives as an h4; "Streaming writes from a
RecordBatchReader" untouched).Are these changes tested?
markdownlint(repo config) passes. Internal anchors verified against thegenerated heading ids.
Are there any user-facing changes?
Docs only.